ice: add extensible relay candidate providers by bclswl0827 · Pull Request #947 · pion/ice

bclswl0827 · 2026-07-29T07:20:43Z

Allow external relay transports to register candidate providers without adding protocol-specific logic to pion-ice. Expose relay local preference configuration and add tests for custom protocols, multiple providers, and invalid candidate cleanup.

Description

This change adds support for extensible relay candidate providers in pion-ice, which enables use cases where traditional TURN is unavailable or undesirable, such as relaying ICE traffic through application-layer transports.

Currently, relay candidates are tightly coupled with built-in relay mechanisms. This makes it difficult for applications that use custom relay transports (for example, relay over WebSocket, proprietary tunneling protocols, or application-specific forwarding services) to integrate with ICE without modifying pion-ice internals.

This PR introduces a provider interface that allows external transports to register their own relay candidate sources. ICE remains transport-agnostic while applications can provide custom relay implementations.

This also exposes relay local preference configuration so applications can control candidate priority when multiple relay providers are available.

Reference issue

none

codecov · 2026-08-01T05:28:22Z

Codecov Report

❌ Patch coverage is 65.21739% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.10%. Comparing base (ec1d554) to head (c89de79).

Files with missing lines	Patch %	Lines
agent.go	76.47%	2 Missing and 2 partials ⚠️
gather.go	33.33%	0 Missing and 4 partials ⚠️

❌ Your patch check has failed because the patch coverage (65.21%) is below the target coverage (70.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #947      +/-   ##
==========================================
+ Coverage   87.94%   88.10%   +0.16%     
==========================================
  Files          46       46              
  Lines        6495     6507      +12     
==========================================
+ Hits         5712     5733      +21     
+ Misses        537      531       -6     
+ Partials      246      243       -3

Flag	Coverage Δ
go	`88.10% <65.21%> (+0.16%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

JoTurk

Is this intended to create a custom transport between the ICE agent and a standard relay? or something else for non standard ICE connections?

If it is only about transporting packets over an arbitrary connection and the interoperability isn't required, couldn't this just be implemented with a custom PacketConn adapter that pipes datagrams over any relay transport without touching ICE itself? we already provides several ways to inject custom network.

Thank you

bclswl0827 · 2026-08-03T14:16:08Z

Is this intended to create a custom transport between the ICE agent and a standard relay? or something else for non standard ICE connections?

Thanks for the review. The goal is actually the second case, I think the important distinction is between packet transport and relay candidate gathering.

couldn't this just be implemented with a custom PacketConn adapter that pipes datagrams over any relay transport without touching ICE itself

A custom PacketConn adapter solves the transport part, but my use case needs to replace the step before a PacketConn is available.

In the current flow, the PacketConn is only attached after the relay candidate has already been created:

candidate, err := NewCandidateRelay(&item.Config)
...
err = a.addCandidate(ctx, candidate, item.Conn)

At that point, addCandidate() starts the candidate, registers it with the agent, creates candidate pairs, and emits the local candidate event.

My use case is different. A non-TURN relay still needs to establish its relay endpoint and provide the information required to construct CandidateRelayConfig (relay address, related address, protocol, etc.). Today that logic only exists in the built-in TURN gathering path.

To be precise, CandidateRelay itself is already transport-agnostic. The coupling is in Agent.gatherCandidatesRelay(), which currently only knows how to obtain relay candidates through TURN. There is also no public way for an application to provide an externally created CandidateRelay together with its associated PacketConn.

This PR makes only that relay gathering step extensible. The provider returns both the CandidateRelayConfig and its associated PacketConn, after which the existing ICE logic, including candidate registration, pairing, and connectivity checks continues unchanged.

JoTurk · 2026-08-03T15:01:36Z

@bclswl0827 then we just need a way to manually add local candidates? I think that would be cleaner than adding an external gatherer.

bclswl0827 · 2026-08-03T15:56:16Z

I agree that could be a cleaner approach than the current one.

If the agent exposed a way to register an externally created local candidate together with its associated PacketConn, the relay allocation could be handled entirely by the application.

Something like this:

func (a *Agent) AddLocalCandidate(
    candidate Candidate,
    conn net.PacketConn,
) error

would allow an application to perform its own relay allocation, construct a CandidateRelay, and then hand it over to the ICE agent for registration.

Internally, this could reuse the existing addCandidate logic, so the ICE state machine and connectivity checks would remain unchanged.

I'm glad to rework the PR in this direction if you think this is a better API.

JoTurk

Thank you @bclswl0827 this is much better API than the custom gatherer, just two nits.

JoTurk · 2026-08-07T07:03:28Z

+// SPDX-FileCopyrightText: 2026 The Pion community <https://pion.ly>
+// SPDX-License-Identifier: MIT


Can you please merge this test file with an existing test file? we're trying to limit how much files we add to /

JoTurk · 2026-08-07T07:07:36Z

+func (a *Agent) AddLocalCandidate(cand Candidate, candidateConn net.PacketConn) error {
+	if cand == nil {
+		return nil
+	}
+	if candidateConn == nil {
+		return ErrCandidatePacketConnNil
+	}
+
+	return a.addCandidate(a.loop, cand, candidateConn)
+}


Can we make sure that a user error with calling this function with the same candidate twice doesn't cause the agent to close the candidate during duplication checks and just returns an error?

ice/agent.go

Lines 1358 to 1364 in c649265

a.log.Debugf("Ignore duplicate candidate: %s", cand)

if err := cand.close(); err != nil {

a.log.Warnf("Failed to close duplicate candidate: %v", err)

}

if err := candidateConn.Close(); err != nil {

a.log.Warnf("Failed to close duplicate candidate connection: %v", err)

}

Maybe we can just add a new parameter to addCandidate so it errors and returns if it detects duplication, while keeping the close behavior for normal path?

JoTurk

I think this approach is good now, Maybe we can also use this to move all the candidates ownership to ice from webrtc in ice@v5

JoTurk · 2026-09-05T21:10:01Z

+	// ErrCandidatePacketConnNil indicates a local candidate was added without
+	// a packet connection.
+	ErrCandidatePacketConnNil = errors.New("candidate packet connection is nil")
+
+	// ErrDuplicateCandidate indicates a local candidate has already been added.
+	ErrDuplicateCandidate = errors.New("candidate already added")


I think these errors should be private.

JoTurk · 2026-09-05T21:11:44Z

@Sean-Der what do you think about this API?

Sean-Der · 2026-09-06T02:39:15Z

@JoTurk I like!

LocalCandidate I was a bit confused by the name. That term is already taken by Remote and Local candidates when I think of ICE. I am not sure of a better name yet

Sean-Der · 2026-09-06T02:40:23Z

Maybe VirtualCandidate? Or something in that vein.

Communicate to the user that it is synthetic. mock isn't right because it isn't test related.

JoTurk · 2026-09-06T02:41:35Z

I agree, will change it to that :)

JoTurk · 2026-09-12T13:08:54Z

@Sean-Der renamed to AddVirtualCandidate :)

Allow registering local candidates with an external packet connection.

JoTurk self-requested a review August 1, 2026 05:24

JoTurk reviewed Aug 3, 2026

View reviewed changes

bclswl0827 force-pushed the main branch 2 times, most recently from 21072cb to cade5b9 Compare August 3, 2026 16:53

bclswl0827 requested a review from JoTurk August 4, 2026 01:46

JoTurk reviewed Aug 7, 2026

View reviewed changes

bclswl0827 requested a review from JoTurk August 8, 2026 07:58

JoTurk reviewed Sep 5, 2026

View reviewed changes

JoTurk force-pushed the main branch 3 times, most recently from b86f680 to 988758d Compare September 12, 2026 13:08

JoTurk approved these changes Sep 12, 2026

View reviewed changes

Add manual local candidate registration

c89de79

Allow registering local candidates with an external packet connection.

JoTurk force-pushed the main branch from 988758d to c89de79 Compare September 12, 2026 13:10

JoTurk merged commit aa9aa79 into pion:main Sep 12, 2026
17 of 18 checks passed

		// SPDX-FileCopyrightText: 2026 The Pion community <https://pion.ly>
		// SPDX-License-Identifier: MIT

	a.log.Debugf("Ignore duplicate candidate: %s", cand)
	if err := cand.close(); err != nil {
	a.log.Warnf("Failed to close duplicate candidate: %v", err)
	}
	if err := candidateConn.Close(); err != nil {
	a.log.Warnf("Failed to close duplicate candidate connection: %v", err)
	}

Uh oh!

Conversation

bclswl0827 commented Jul 29, 2026

Description

Reference issue

Uh oh!

codecov Bot commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

JoTurk left a comment

Choose a reason for hiding this comment

Uh oh!

bclswl0827 commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JoTurk commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bclswl0827 commented Aug 3, 2026

Uh oh!

JoTurk left a comment

Choose a reason for hiding this comment

Uh oh!

JoTurk Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk left a comment

Choose a reason for hiding this comment

Uh oh!

JoTurk Sep 5, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk commented Sep 5, 2026

Uh oh!

Sean-Der commented Sep 6, 2026

Uh oh!

Sean-Der commented Sep 6, 2026

Uh oh!

JoTurk commented Sep 6, 2026

Uh oh!

JoTurk commented Sep 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Aug 1, 2026 •

edited

Loading

bclswl0827 commented Aug 3, 2026 •

edited

Loading

JoTurk commented Aug 3, 2026 •

edited

Loading